﻿<HTML>

<HEAD>
  <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8" />  
  <TITLE>Sample and User Projects</TITLE>
  <LINK HREF="doc.css" REL=STYLESHEET>
</HEAD>


<BODY>


<!-- ============================================ -->


  <H1>Sample and User Projects</H1>

  <A HREF="solvers.html">[Previous]</A><A HREF="style.html">[Next]</A><A HREF="../index.html">[Home]</A>

  <H2>Contents</H2>

  <UL>
    <LI><A HREF="#overview">Overview</A></LI> 
    <LI><A HREF="#generic">Generic Projects</A></LI> 
    <LI><A HREF="#onemax">ONE-MAX Projects</A></LI> 
    <LI><A HREF="#maxsat">MAX-SAT Projects</A></LI> 
    <LI><A HREF="#building">Building and Running Projects</A></LI> 
    <LI><A HREF="#creating">How to Create User Projects</A></LI> 
  </UL>


<!-- ============================================ -->


  <A NAME="overview"></A>
  <H3>Overview</H3>

  <P>
    There are several sample projects provided with the HeO library.
    The main goal of these projects is to help users to understand the HeO architecture.
    All projects can be compiled under Windows and Linux (please check <A HREF="heo.html#sysreq">System Requirements</A>).
   </P> 

  <P>
    All sample and user projects are stored in the <TT CLASS="folder">/heo/projects</TT> folder.
    Projects for different optimization problems are stored in separate subfolders.
  </P> 


<!-- ============================================ -->


  <A NAME="generic"></A>
  <H3>Generic Projects</H3>

  <P>
    In the generic projects no optimization problem is solved. 
    The goal of these projects is to demonstrate the usage of the HeO solvers. 
    Problem-specific classes in these projects implement only those methods that are specific to the particular optimization technique.
    These methods are implemented as program stubs that perform no action and allow to compile the projects without errors.
  </P> 


  <P>
    The generic projects are stored in the <TT CLASS="folder">/heo/projects/generic</TT> folder. 
    Projects for different optimization techniques are stored in separate subfolders (e.g., <TT CLASS="folder">/heo/projects/generic/ga</TT>, <TT CLASS="folder">/heo/projects/generic/sa</TT>).
    Projects for different solvers of the same optimization technique are stored in separate subfolders (e.g., <TT CLASS="folder">/heo/projects/generic/ga/mpi</TT>, <TT CLASS="folder">/heo/projects/generic/ga/omp</TT>).
  </P> 


  <P>
    The input files for the generic projects are stored in the <TT CLASS="folder">/heo/problems/generic</TT> folder and contain only the zero value of the dummy variable.
  </P> 


<!-- ============================================ -->


  <A NAME="onemax"></A>
  <H3>ONE-MAX Projects</H3>

  <P>
    The ONE-MAX problem is a simple optimization problem that is often used to test the optimization algorithms.  
    Its goal is to maximize the number of 1s in a bit string.
  </P> 


  <P>
    The ONE-MAX projects are stored in the respective subfolders of the <TT CLASS="folder">/heo/projects/onemax</TT> folder.
    The input files for these projects are stored in the <TT CLASS="folder">/heo/problems/onemax</TT> folder and contain the number of bits in the string.
  </P> 


<!-- ============================================ -->


  <A NAME="maxsat"></A>
  <H3>MAX-SAT Projects</H3>

  <P>
    In the Maximum Satisfiability Problem (MAX-SAT) a Boolean formula in conjunctive normal form (CNF) is given.
    The goal of the problem is to find a set of truth variables that maximizes the number of satisfied clauses.
  </P> 
  
  <P>
    The MAX-SAT projects are stored in the respective subfolders of the <TT CLASS="folder">/heo/projects/maxsat</TT> folder.
    The input files for these projects are stored in the <TT CLASS="folder">/heo/problems/maxsat</TT> folder and have to be in CNF format without comments as it is shown below: 
  </P> 

  <DIV CLASS="code">
    p cnf 500 1000<BR>
    300 -128 0<BR>
    212 -210 188 0<BR>
    -139 123 -33 2 -5 0<BR>
    190 -358 202 0<BR>
    -417 101 0<BR>
    ...
  </DIV>

  <P>
    The first string of the file specifies that this problem is in CNF format and has 500 variables and 1000 clauses. 
    Next lines describe the clauses of the Boolean formula.
    In the above example the formula is as follows: 
    (<I>x<SUB>300</SUB></I>&or;&not;<I>x<SUB>128</SUB></I>)&and;(<I>x<SUB>212</SUB></I>&or;&not;<I>x<SUB>210</SUB></I>&or;<I>x<SUB>188</SUB></I>)&and;&hellip;
  </P> 
  

<!-- ============================================ -->


  <A NAME="building"></A>
  <H3>Building and Running Projects</H3>


  <P>
    <B>Building and Running Projects under Linux</B>
  </P>

  <UL>
    <LI>To compile the desired project change to its folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/ga/mpi</TT>) and run <TT>make</TT> command.</LI>
    <LI>To compile all projects (except generic) change to the <TT CLASS="folder">/heo/projects/all</TT> folder and run <TT>make</TT> command.</LI>
    <LI>To run the compiled project use the appropriate command file in the <TT CLASS="folder">/heo/projects/&lt;problem&nbsp;name&gt;/!run</TT> folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/!run</TT>).</LI>
    <LI>The results of the project runs are stored in the <TT CLASS="folder">/heo/projects/&lt;problem&nbsp;name&gt;/!res</TT> folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/!res</TT>).</LI>
  </UL> 

  <P>
    <B>Note.</B> The GCC compiler is assumed by default for Linux. If you wish to use another compiler you may need to modify the following files in the <TT CLASS="folder">/heo/src/heo/include</TT> folder: 
  </P>

  <UL>
    <LI><TT>mpi.makefile</TT>.</LI> 
    <LI><TT>omp.makefile</TT>.</LI> 
    <LI><TT>common.makefile</TT>.</LI> 
  </UL>

  <P>
    The first two files contain the MPI "wrapper" compiler name (<TT>HEO_CXX = mpiCC</TT>) and the OpenMP compiler name (<TT>HEO_CXX = g++</TT>) respectively and their options.
    The third file contains all information for building the projects.
  </P>

  <P>
     For example, if you wish to build OpenMP projects using Intel C++ Compiler you have to modify the <TT>omp.makefile</TT> as follows:
  </P>

  <DIV CLASS="code">
    HEO_CXX = icpc<BR>
    HEO_CXXFLAGS = -I. -I$(HEO_PATH) -openmp -openmp-lib=compat
  </DIV>

  <P>
     Building MPI projects using Intel C++ Compiler under Linux may be more complicated.
     If the <TT>mpicxx</TT> is a text script you can find the <TT>g++</TT> string in it and replace it with <TT>icpc</TT>.
     If the <TT>mpicxx</TT> isn't a text script then you have to build the MPI itself using Intel C++ Compiler (please refer to MPI documentation).
  </P>



  <P>
    <B>Building and Running Projects under Windows</B>
  </P>

  <UL>
    <LI>To compile the desired project change to its folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/ga/mpi</TT>), run the <TT>*.sln</TT> file, select the <TT>Release</TT> configuration and build the project.</LI>
    <LI>To compile all projects (except generic) change to the <TT CLASS="folder">/heo/projects/all</TT> folder, run <TT>all.sln</TT> file, select the <TT>Release</TT> configuration and build the projects.</LI>
    <LI>To run the compiled project use the appropriate command file in the <TT CLASS="folder">/heo/projects/&lt;problem&nbsp;name&gt;/!run</TT> folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/!run</TT>).</LI>
    <LI>The results of the project runs are stored in the <TT CLASS="folder">/heo/projects/&lt;problem&nbsp;name&gt;/!res</TT> folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/!res</TT>).</LI>
  </UL> 

  <P>
    <B>Note.</B> The MS VC++ compiler is assumed by default for Windows. If you wish to use Intel C++ Compiler you have to integrate it with the MS Visual Studio. 
  </P>


<!-- ============================================ -->


  <A NAME="creating"></A>
  <H3>How to Create User Projects</H3>

  <P>
    The library provides special wizards that ease the process of creating user projects.
    Wizards for Linux and Windows systems are called <TT>wizard.sh</TT> and <TT>wizard.vbs</TT> respectively. 
    They are stored in the <TT CLASS="folder">/heo/projects</TT> folder.
  </P>


  <P>
    To create a new project: 
  </P>

  <OL>
    <LI>Run the wizard and follow the instructions.
        All necessary subfolders and source files in the <TT CLASS="folder">/heo/projects</TT> and <TT CLASS="folder">/heo/problems</TT> folders will be created automatically.</LI>
    <LI>Modify problem-specific classes.</LI> 
    <LI>Copy the input files containing problem instances to the <TT CLASS="folder">/heo/problems/&lt;problem&nbsp;name&gt;</TT> folder.</LI>
    <LI>Modify the string <TT>input_file=...</TT> in the appropriate <TT>*.ini</TT> files.</LI>
    <LI>If needed, modify the appropriate command files in the <TT CLASS="folder">/heo/projects/&lt;problem&nbsp;name&gt;/!run</TT> folder.</LI>
  </OL>

  <P>
    <B>Note.</B> If the <TT>*.ini</TT> file indicated in the command file does not exist it will be created automatically after the first project run and its parameters will be set to the default values.
  </P>


<H2>&nbsp;</H2>

<A HREF="solvers.html">[Previous]</A><A HREF="style.html">[Next]</A><A HREF="../index.html">[Home]</A>


<!-- ============================================ -->


</BODY>

</HTML>


